<?xml version="1.0" encoding="ascii"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>esapi.access_reference_map.AccessReferenceMap</title>
  <link rel="stylesheet" href="epydoc.css" type="text/css" />
  <script type="text/javascript" src="epydoc.js"></script>
</head>

<body bgcolor="white" text="black" link="blue" vlink="#204080"
      alink="#204080">
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="esapi-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

      <th class="navbar" width="100%"></th>
  </tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0">
  <tr valign="top">
    <td width="100%">
      <span class="breadcrumbs">
        <a href="esapi-module.html">Package&nbsp;esapi</a> ::
        <a href="esapi.access_reference_map-module.html">Module&nbsp;access_reference_map</a> ::
        Class&nbsp;AccessReferenceMap
      </span>
    </td>
    <td>
      <table cellpadding="0" cellspacing="0">
        <!-- hide/show private -->
        <tr><td align="right"><span class="options">[<a href="javascript:void(0);" class="privatelink"
    onclick="toggle_private();">hide&nbsp;private</a>]</span></td></tr>
        <tr><td align="right"><span class="options"
            >[<a href="frames.html" target="_top">frames</a
            >]&nbsp;|&nbsp;<a href="esapi.access_reference_map.AccessReferenceMap-class.html"
            target="_top">no&nbsp;frames</a>]</span></td></tr>
      </table>
    </td>
  </tr>
</table>
<!-- ==================== CLASS DESCRIPTION ==================== -->
<h1 class="epydoc">Class AccessReferenceMap</h1><p class="nomargin-top"><span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap">source&nbsp;code</a></span></p>
<pre class="base-tree">
object --+
         |
        <strong class="uidshort">AccessReferenceMap</strong>
</pre>

<dl><dt>Known Subclasses:</dt>
<dd>
      <ul class="subclass-list">
<li><a href="esapi.reference.random_access_reference_map.RandomAccessReferenceMap-class.html">reference.random_access_reference_map.RandomAccessReferenceMap</a></li>  </ul>
</dd></dl>

<hr />
<p>The AccessReferenceMap interface is used to map from a set of internal
  direct object references to a set of indirect references that are safe to
  disclose publicly. This can be used to help protect database keys, 
  filenames, and other types of direct object references. As a rule, 
  developers should not expose their direct object references as it enables
  attackers to attempt to manipulate them.</p>
  <p>Indirect references are handled as strings to facilitate their use in 
  HTML. Implementations can generate simple integers or more complicated 
  random character strings as indirect references. Implementations should 
  probably add a constructor that takes a list of direct references.</p>
  <p>Note that in addition to defeating all forms of parameter tampering 
  attacks, there is a side benefit of the AccessReferenceMap. Using random 
  strings as indirect object references, as opposed to simple integers, 
  makes it impossible for attacker to guess valid identifiers. So if 
  per-user AccessReferenceMaps are used, then request forgery (CSRF) 
  attacks will also be prevented.</p>

<hr />
<div class="fields">      <p><strong>Author:</strong>
        Craig Younkins (craig.younkins@owasp.org)
      </p>
</div><!-- ==================== INSTANCE METHODS ==================== -->
<a name="section-InstanceMethods"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Instance Methods</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-InstanceMethods"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="esapi.access_reference_map.AccessReferenceMap-class.html#__init__" class="summary-sig-name">__init__</a>(<span class="summary-sig-arg">self</span>)</span><br />
      x.__init__(...) initializes x; see x.__class__.__doc__ for signature</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.__init__">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="esapi.access_reference_map.AccessReferenceMap-class.html#get_indirect_reference" class="summary-sig-name">get_indirect_reference</a>(<span class="summary-sig-arg">self</span>,
        <span class="summary-sig-arg">direct_ref</span>)</span><br />
      Get a safe indirect reference to use in place of a potentially 
      sensitive direct object reference.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.get_indirect_reference">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="esapi.access_reference_map.AccessReferenceMap-class.html#get_direct_reference" class="summary-sig-name">get_direct_reference</a>(<span class="summary-sig-arg">self</span>,
        <span class="summary-sig-arg">indirect_ref</span>)</span><br />
      Get the original direct object reference from an indirect reference.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.get_direct_reference">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="esapi.access_reference_map.AccessReferenceMap-class.html#add_direct_reference" class="summary-sig-name">add_direct_reference</a>(<span class="summary-sig-arg">self</span>,
        <span class="summary-sig-arg">direct_ref</span>)</span><br />
      Adds a direct reference to the AccessReferenceMap, then generates and
      returns an associated indirect reference.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.add_direct_reference">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="esapi.access_reference_map.AccessReferenceMap-class.html#remove_direct_reference" class="summary-sig-name">remove_direct_reference</a>(<span class="summary-sig-arg">self</span>,
        <span class="summary-sig-arg">direct_ref</span>)</span><br />
      Removes a direct reference and its associated indirect reference from
      the AccessReferenceMap.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.remove_direct_reference">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <td><span class="summary-sig"><a href="esapi.access_reference_map.AccessReferenceMap-class.html#update" class="summary-sig-name">update</a>(<span class="summary-sig-arg">self</span>,
        <span class="summary-sig-arg">set</span>)</span><br />
      Updates the AccessReferenceMap with a new set of direct references, 
      maintaining any existing indirect references associated with items 
      that are in the new list.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.update">source&nbsp;code</a></span>
            
          </td>
        </tr>
      </table>
      
    </td>
  </tr>
  <tr>
    <td colspan="2" class="summary">
    <p class="indent-wrapped-lines"><b>Inherited from <code>object</code></b>:
      <code>__delattr__</code>,
      <code>__format__</code>,
      <code>__getattribute__</code>,
      <code>__hash__</code>,
      <code>__new__</code>,
      <code>__reduce__</code>,
      <code>__reduce_ex__</code>,
      <code>__repr__</code>,
      <code>__setattr__</code>,
      <code>__sizeof__</code>,
      <code>__str__</code>,
      <code>__subclasshook__</code>
      </p>
    </td>
  </tr>
</table>
<!-- ==================== PROPERTIES ==================== -->
<a name="section-Properties"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Properties</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Properties"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
  <tr>
    <td colspan="2" class="summary">
    <p class="indent-wrapped-lines"><b>Inherited from <code>object</code></b>:
      <code>__class__</code>
      </p>
    </td>
  </tr>
</table>
<!-- ==================== METHOD DETAILS ==================== -->
<a name="section-MethodDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Method Details</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-MethodDetails"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
</table>
<a name="__init__"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">__init__</span>(<span class="sig-arg">self</span>)</span>
    <br /><em class="fname">(Constructor)</em>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.__init__">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>x.__init__(...) initializes x; see x.__class__.__doc__ for 
  signature</p>
  <dl class="fields">
    <dt>Overrides:
        object.__init__
        <dd><em class="note">(inherited documentation)</em></dd>
    </dt>
  </dl>
</td></tr></table>
</div>
<a name="get_indirect_reference"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">get_indirect_reference</span>(<span class="sig-arg">self</span>,
        <span class="sig-arg">direct_ref</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.get_indirect_reference">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>Get a safe indirect reference to use in place of a potentially 
  sensitive direct object reference. Developers should use this call when 
  building URLs, form fields, hidden fields, etc... to help protect their 
  private implementation information.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>direct_ref</code></strong> - the direct object you want to reference</li>
    </ul></dd>
    <dt>Returns:</dt>
        <dd>the indirect reference</dd>
  </dl>
</td></tr></table>
</div>
<a name="get_direct_reference"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">get_direct_reference</span>(<span class="sig-arg">self</span>,
        <span class="sig-arg">indirect_ref</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.get_direct_reference">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>Get the original direct object reference from an indirect reference. 
  Developers should use this when they get an indirect reference from a 
  request to translate it back into the real direct reference. If an 
  invalid indirect reference is requested, then an AccessControlException 
  is raised.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>indirect_ref</code></strong> - the indirect object reference</li>
    </ul></dd>
    <dt>Returns:</dt>
        <dd>the direct reference</dd>
    <dt>Raises:</dt>
    <dd><ul class="nomargin-top">
        <li><code><strong class='fraise'><a href="esapi.exceptions.AccessControlException-class.html">AccessControlException</a></strong></code> - If no direct reference exists for the specified indirect reference</li>
    </ul></dd>
  </dl>
</td></tr></table>
</div>
<a name="add_direct_reference"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">add_direct_reference</span>(<span class="sig-arg">self</span>,
        <span class="sig-arg">direct_ref</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.add_direct_reference">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>Adds a direct reference to the AccessReferenceMap, then generates and 
  returns an associated indirect reference.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>direct_ref</code></strong> - the direct reference</li>
    </ul></dd>
    <dt>Returns:</dt>
        <dd>the corresponding indirect reference</dd>
  </dl>
</td></tr></table>
</div>
<a name="remove_direct_reference"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">remove_direct_reference</span>(<span class="sig-arg">self</span>,
        <span class="sig-arg">direct_ref</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.remove_direct_reference">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>Removes a direct reference and its associated indirect reference from 
  the AccessReferenceMap.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>direct_ref</code></strong> - the direct reference to remove</li>
    </ul></dd>
    <dt>Returns:</dt>
        <dd>the corresponding indirect reference</dd>
  </dl>
</td></tr></table>
</div>
<a name="update"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">update</span>(<span class="sig-arg">self</span>,
        <span class="sig-arg">set</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="esapi.access_reference_map-pysrc.html#AccessReferenceMap.update">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>
  
  <p>Updates the AccessReferenceMap with a new set of direct references, 
  maintaining any existing indirect references associated with items that 
  are in the new list. New indirect references could be generated every 
  time, but that might mess up anything that previously used an indirect 
  reference, such as a URL parameter.</p>
  <dl class="fields">
    <dt>Parameters:</dt>
    <dd><ul class="nomargin-top">
        <li><strong class="pname"><code>set</code></strong> - An iterable of direct references.</li>
    </ul></dd>
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="esapi-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

      <th class="navbar" width="100%"></th>
  </tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%%">
  <tr>
    <td align="left" class="footer">
    Generated by Epydoc 3.0.1 on Sun Nov  8 16:04:21 2009
    </td>
    <td align="right" class="footer">
      <a target="mainFrame" href="http://epydoc.sourceforge.net"
        >http://epydoc.sourceforge.net</a>
    </td>
  </tr>
</table>

<script type="text/javascript">
  <!--
  // Private objects are initially displayed (because if
  // javascript is turned off then we want them to be
  // visible); but by default, we want to hide them.  So hide
  // them unless we have a cookie that says to show them.
  checkCookie();
  // -->
</script>
</body>
</html>
